Inside Macintosh: Imaging with QuickDraw
All graphics operations are performed in graphics ports. Before a color graphics port can be used, it must be allocated with the OpenCPort procedure and initialized with the InitCPort procedure. Normally, your application does not call these procedures directly. Instead, your application creates a graphics port by using the GetNewCWindow or NewCWindow function (described in the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials ) or the NewGWorld function (described in the chapter "Offscreen Graphics Worlds" in this book). These functions automatically call OpenCPort , which in turn calls InitCPort .
To dispose of a color graphics port when you are finished using a color window, you normally use the DisposeWindow procedure (if you let the Window Manager allocate memory for the window) or the CloseWindow procedure (if you allocated memory for the window). You use the DisposeGWorld procedure when you are finished with a color graphics port for an offscreen graphics world. These routines automatically call the CloseCPort procedure. If you use the CloseWindow procedure, you also dispose of the window record containing the graphics port by calling the Memory Manager procedure DisposePtr .
The OpenCPort procedure allocates space for and initializes a color graphics port. The Window Manager calls OpenCPort for every color window that it creates, and the NewGWorld procedure calls OpenCPort for every offscreen graphics world that it creates on a Color QuickDraw computer.
PROCEDURE OpenCPort (port: CGrafPtr);
The OpenCPort procedure is analogous to OpenPort (described in the chapter "Basic QuickDraw"), except that OpenCPort opens a CGrafPort record instead of a GrafPort record. The OpenCPort procedure is called by the Window Manager's NewCWindow and GetNewCWindow procedures, as well as by the Dialog Manager when the appropriate color resources are present. The OpenCPort procedure allocates storage for all the structures in the CGrafPort record, and then calls InitCPort to initialize them. The InitCPort procedure does not allocate a color table for the PixMap record for the color graphics port; instead, InitCPort copies the handle to the current device's CLUT into the PixMap record. The initial values for the CGrafPort record are shown in Table 4-3 .
The additional structures allocated are the portPixMap , pnPixPat , fillPixPat , bkPixPat , and grafVars handles, as well as the fields of the GrafVars record.
The OpenCPort procedure uses the InitCPort procedure to initialize a color graphics port.
PROCEDURE InitCPort (port: CGrafPtr);
The InitCPort procedure is analogous to InitPort (described in the chapter "Basic QuickDraw"), except InitCPort initializes a CGrafPort record instead of a GrafPort record. The InitCPort procedure does not allocate any storage; it merely initializes all the fields in the CGrafPort and GrafVars records to the default values shown in Table 4-3 .
The PixMap record for the new color graphics port is set to be the same as the current device's PixMap record. This allows you to create an offscreen graphics world that is identical to the screen's port for drawing offscreen. If you want to use a different set of colors for offscreen drawing, you should create a new GDevice record and set it as the current GDevice record before opening the CGrafPort record.
Remember that InitCPort does not copy the data from the current device's CLUT to the color table for the graphics port's PixMap record. It simply replaces whatever is in the PixMap record's pmTable field with a copy of the handle to the current device's CLUT.
If you try to initialize a GrafPort record using InitCPort , it simply returns without doing anything.
The CloseCPort procedure closes a color graphics port. The Window Manager calls this procedure when you close or dispose of a window, and the DisposeGWorld procedure calls it when you dispose of an offscreen graphics world containing a color graphics port.
PROCEDURE CloseCPort (port: CGrafPtr);
The CloseCPort procedure releases the memory allocated to the CGrafPort record. It disposes of the visRgn , clipRgn , bkPixPat , pnPixPat , fillPixPat , and grafVars handles. It also disposes of the graphics port's pixel map, but it doesn't dispose of the pixel map's color table (which is really owned by the GDevice record). If you have placed your own color table into the pixel map, either dispose of it before calling CloseCPort or store another reference.